Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / dmalloc.zip / INSTALL.LIB / DOC / DMALLOC.DOC < prev next >

Wrap

Text File | 1992-11-01 | 132.2 KB | 3,530 lines

******************************************************** DDDDD MM MM (TM) DD DD MMM MMM DD DD MMMMMMMM DD DD MMMMMMMM AA LLLL LLLL OOO CCCC DD DD MM MM MM AAAA LL LL OO OO CC CC DD DD MM MM AA AA LL LL OO OO CC DD DD MM MM AA AA LL LL OO OO CC DD DD MM MM AAAAAA LL L LL L OO OO CC DD DD MM MM AA AA LL LL LL LL OO OO CC CC DDDDD MM MM AA AA LLLLLLL LLLLLLL OOO CCCC ******************************************************** v 1.0 The C Language Malloc Debugger by Ernest E. Vogelsinger ┌─────────┐ ┌─────┴───┐ │ (R) ──│ │o │────────────────── │ ┌─────┴╨──┐ │ Association of │ │ │─┘ Shareware └───│ o │ Professionals ──────│ ║ │──────────────────── └────╨────┘ MEMBER ***************** IMPORTANT WARRANTY INFORMATION **************** DMalloc, Version 1.00 *** PLEASE READ THIS INFORMATION CAREFULLY *** TRIAL USE (SHAREWARE EVALUATION VERSION) WARRANTY: -------------------------------------------------- The Shareware evaluation (trial use) version is provided AS IS. Ernest Vogelsinger MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE. REGISTERED VERSION ONLY WARRANTY: --------------------------------- Ernest Vogelsinger warrants the physical diskette(s) and physical documentation provided with registered versions to be free of defects in materials and workmanship for a period of ninety days from the date of registration. If Ernest Vogelsinger receives notification within the warranty period of defects in materials or workmanship, and such notification is determined by Ernest Vogelsinger to be correct, Ernest Vogelsinger will replace the defective diskette(s) or documentation. The entire and exclusive liability and remedy for breach of this Limited Warranty shall be limited to replacement of defective diskette(s) or documentation and shall not include or extend to any claim for or right to recover any other damages, including but not limited to, loss of profit, data, or use of the software, or special, incidental, or consequential damages or other similar claims, even if Ernest Vogelsinger has been specifically advised of the possibility of such damages. In no event will Ernest Vogelsinger's liability for any damages to you or any other person ever exceed the lower of suggested list price or actual price paid for the license to use the software, regardless of any form of the claim. Ernest Vogelsinger SPECIFICALLY DISCLAIMS ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, ANY IMPLIED WARRANTY OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE. ***************** IMPORTANT WARRANTY INFORMATION **************** DMalloc is a trademark of Ernest Vogelsinger. Soft-ICE and Bounds-Checker are registered trademarks of Nu-Mega Technologies, Inc. Microsoft, MS-DOS, and CodeView are registered trademarks of Microsoft Corp. Any other product names used herein are for identification purposes only and may be trademarks or registered trademarks of their respective companies. 1991-1992 Ernest Vogelsinger, Vienna, Austria 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1. What is DMalloc?. . . . . . . . . . . . . . . . . . . . . . . . 1 1.2. Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3. Why DMalloc Instead of a BRAND X Heap Checker . . . . . . . . . 1 1.4. Summary of Features . . . . . . . . . . . . . . . . . . . . . . 2 1.5. What is Shareware . . . . . . . . . . . . . . . . . . . . . . . 2 1.6. DMalloc Unregistered Evaluation Version . . . . . . . . . . . . 3 1.7. Registration. . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.7.1. Registering Your Evaluation Copy . . . . . . . . . . . . 5 1.8. Distribution Policies . . . . . . . . . . . . . . . . . . . . . 5 1.9. Association of Shareware Professionals Ombudsman. . . . . . . . 6 2. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1. From a Compressed Archive . . . . . . . . . . . . . . . . . . . 7 2.2. From a Distribution Disk. . . . . . . . . . . . . . . . . . . . 7 2.3. Checking the Completed Installation . . . . . . . . . . . . . . 7 2.4. Documentation . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.4.1. Registration Form. . . . . . . . . . . . . . . . . . . . 8 2.4.2. The Manual . . . . . . . . . . . . . . . . . . . . . . . 9 2.5. A Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.6. Where to from here? . . . . . . . . . . . . . . . . . . . . . . 10 2.7. Support & Thanks. . . . . . . . . . . . . . . . . . . . . . . . 10 3. The Demonstration Program. . . . . . . . . . . . . . . . . . . . . . . 12 3.1. Compiling the Demo Program. . . . . . . . . . . . . . . . . . . 12 3.2. Running the Demo. . . . . . . . . . . . . . . . . . . . . . . . 12 3.3. DMalloc Startup . . . . . . . . . . . . . . . . . . . . . . . . 13 3.4. Heap Overview . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.5. Total Heap Status . . . . . . . . . . . . . . . . . . . . . . . 14 3.6. Detecting Heap Problems . . . . . . . . . . . . . . . . . . . . 14 3.7. Invalid Pointer Warning . . . . . . . . . . . . . . . . . . . . 15 3.8. Determining Action, Setting Breakpoints . . . . . . . . . . . . 15 3.9. Null Pointer Assignments. . . . . . . . . . . . . . . . . . . . 16 3.10. Fatal Heap Errors. . . . . . . . . . . . . . . . . . . . . . . 16 4. Dynamic Memory and DMalloc . . . . . . . . . . . . . . . . . . . . . . 17 4.1. Dynamic Memory Layout . . . . . . . . . . . . . . . . . . . . . 17 4.2. DMalloc and Dynamic Memory. . . . . . . . . . . . . . . . . . . 17 4.3. Tracking the Functions. . . . . . . . . . . . . . . . . . . . . 18 4.4. Checking the Heap . . . . . . . . . . . . . . . . . . . . . . . 18 4.5. Types of Heap Corruption. . . . . . . . . . . . . . . . . . . . 19 4.5.1. Lead Corruption. . . . . . . . . . . . . . . . . . . . . 19 4.5.2. Trail Corruption . . . . . . . . . . . . . . . . . . . . 19 4.5.3. Odd/Even Problem . . . . . . . . . . . . . . . . . . . . 19 4.5.4. Mavericks. . . . . . . . . . . . . . . . . . . . . . . . 19 4.6. Null Pointer Assignments. . . . . . . . . . . . . . . . . . . . 20 4.7. Far Null Pointer Assignments. . . . . . . . . . . . . . . . . . 20 4.8. Watchpoints . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.9. Savepoints. . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5. DMalloc In Detail. . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.1. About DMalloc Windows . . . . . . . . . . . . . . . . . . . . . 21 5.2. Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.3. Information Window. . . . . . . . . . . . . . . . . . . . . . . 22 5.3.1. "You can" - Select the Next Action . . . . . . . . . . . 22 5.3.2. "Breakpoint:". . . . . . . . . . . . . . . . . . . . . . 23 5.4. Setup Window. . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.4.1. Alert on problem . . . . . . . . . . . . . . . . . . . . 23 ----- DMalloc -------------------------------------- Table of Contents ------ 5.4.2. Popup on saved . . . . . . . . . . . . . . . . . . . . . 24 5.4.3. Cycles for popup . . . . . . . . . . . . . . . . . . . . 24 5.4.4. Heap check cycles. . . . . . . . . . . . . . . . . . . . 24 5.4.5. Popup for file/line. . . . . . . . . . . . . . . . . . . 24 5.4.6. Startup screen . . . . . . . . . . . . . . . . . . . . . 24 5.4.7. Shutdown screen. . . . . . . . . . . . . . . . . . . . . 25 5.4.8. Alternate monitor. . . . . . . . . . . . . . . . . . . . 25 5.4.9. Number of handles. . . . . . . . . . . . . . . . . . . . 25 5.5. Colors Window . . . . . . . . . . . . . . . . . . . . . . . . . 26 5.6. Heap Entries Window . . . . . . . . . . . . . . . . . . . . . . 27 5.6.1. Detecting Corrupted Entries. . . . . . . . . . . . . . . 29 5.6.2. "Repairing" Corrupted Entries. . . . . . . . . . . . . . 29 5.6.3. Watchpoints ("Tags") . . . . . . . . . . . . . . . . . . 29 5.6.4. Savepoints . . . . . . . . . . . . . . . . . . . . . . . 30 5.7. Selection Window. . . . . . . . . . . . . . . . . . . . . . . . 30 5.8. Dump Window . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.8.1. Editing Data . . . . . . . . . . . . . . . . . . . . . . 31 5.9. Heap Status Window. . . . . . . . . . . . . . . . . . . . . . . 32 5.10. The Configuration File . . . . . . . . . . . . . . . . . . . . 32 5.10.1. Configuring the Library . . . . . . . . . . . . . . . . 33 6. How to use DMalloc . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.1. Linking DMalloc to the Program. . . . . . . . . . . . . . . . . 33 6.1.1. Using Different Compilers. . . . . . . . . . . . . . . . 33 6.1.2. Using Overlay Linkers. . . . . . . . . . . . . . . . . . 33 6.2. Recompiling . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.2.1. Effects and Side-Effects when using the _DMALLOC switch. . . . . . . . . . . . . . . . . . . . . . 34 6.3. Calling the DMalloc API . . . . . . . . . . . . . . . . . . . . 35 6.4. DMalloc and Spawn . . . . . . . . . . . . . . . . . . . . . . . 35 6.5. DMalloc and Video . . . . . . . . . . . . . . . . . . . . . . . 35 6.5.1. The Relocatable Screen Interface (RLSI). . . . . . . . . 36 6.5.2. Calling RLSI . . . . . . . . . . . . . . . . . . . . . . 36 6.6. DMalloc and Debuggers . . . . . . . . . . . . . . . . . . . . . 36 6.6.1. Soft-ICE(tm) . . . . . . . . . . . . . . . . . . . . . . 37 6.6.2. CodeView(r). . . . . . . . . . . . . . . . . . . . . . . 37 6.6.3. Other Debuggers. . . . . . . . . . . . . . . . . . . . . 37 6.7. DMalloc and Bounds-Checker(r) . . . . . . . . . . . . . . . . . 37 6.8. DMalloc and atexit() processing . . . . . . . . . . . . . . . . 38 7. The Programming API. . . . . . . . . . . . . . . . . . . . . . . . . . 38 7.1. Activating the API. . . . . . . . . . . . . . . . . . . . . . . 38 7.2. Removing the API Calls. . . . . . . . . . . . . . . . . . . . . 38 8. API Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 9. Problem Solving, and Frequently Asked Questions. . . . . . . . . . . . 43 Appendix A - The Library Serialization Program DMSerial . . . . . . . . . 46 Appendix B - The Library Configuration Program DMConfig . . . . . . . . . 47 Appendix C - The Legal Department (License Agreement) . . . . . . . . . . 48 Appendix D - How to Send Email to Compuserve. . . . . . . . . . . . . . . 49 D.1 How to obtain a CompuServe Account . . . . . . . . . . . . . . . 49 D.2 MCI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 D.3 Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 D.4 Telex, Twx . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 D.5 X.400. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 D.6 MHS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 ----- DMalloc -------------------------------------- Table of Contents ------ 1. Introduction 1.1. What is DMalloc? DMalloc is a full-featured, convenient, windowed pop-up dynamic memory debugger for C language applications. It monitors heap integrity and the dynamic memory requirements of an application. From a technical point of view DMalloc is a library that is linked with the program's object fi- les. 1.2. Requirements DMalloc is currently available for Microsoft(r) C compilers (v.5.1, 6+, and 7). Different compiler versions may be sup- ported with future upgrades. DMalloc can only be used with the "large" memory model (far code, far data).(1) DOS version should be 3.30 or above.(2) DMalloc will add about 41kB to code and data size, and - depending on the setup - 2 to 141 kB of dynamic (far) memo- ry. 1.3. Why DMalloc Instead of a BRAND X Heap Checker DMalloc checks the integrity of dynamic memory. Unlike ot- her packages, it monitors the allocated memory units them- selves, instead of tracking out-of-bounds segment accesses. Thus it is an ideal companion to 386-based bound checking utilities such as Bounds-Checker(tm). For more information on segments and allocation units refer to section 4, page 17. You don't need to recompile a single source module. DMalloc tracks all calls to memory allocation/deallocation, even in third-party code and libraries. Null pointer assignments are detected much earlier than by the runtime library (which detects them at the end of the program). And, as a special feature for the large memory model, even assignments to far null pointers (the interrupt table) are detected and repaired (if possible) to keep the interrupt table intact. DMalloc can cooperate with other debuggers. Special support has been built in for CodeView(r) and Soft-ICE(tm) debug- gers. DMalloc can be used as a background watchdog as well as to interactively review the requirements and fragmentation status of the dynamic heap. DMalloc supports an alternate monitor to allow debugging of graphical applications. ____________________ 1 Future versions may support different memory models. 2 DMalloc was tested with DOS versions 3.30, 4.01, and 5.00. However, nothing special is needed from DOS, so other versions should do as well. ----- DMalloc ------------------------------------------- Page 1 of 52 ------ DMalloc can remember corrupted allocation units from one session to the next, allowing you to monitor suspect units from the moment of their allocation. DMalloc provides a rich API to allow fine-tuning of debug- ging setups from within the source code. DMalloc is shareware, allowing you to fully evaluate it for 30 days. If you don't like it, you don't pay for it. Howe- ver, DMalloc is a very professional debug utility, and not playware. 1.4. Summary of Features ■ Tracking of allocation and deallocation of dynamic me- mory ■ Integrity check on every allocated unit ■ Integrity check on the data segment null region (null pointer assignment error) ■ Integrity check and repair on the far-null region (the interrupt table) ■ Automatic pop-up when a heap problem is encountered ■ Interactive pop-up by pressing [PrtSc] ■ Automatic pop-up when allocating memory that has been corrupted in the last debug session, or that has been selected to be saved ■ Pop-up when freeing/reallocating/expanding selected units (Watchpoint feature) ■ Graceful program termination when the heap is destroyed and the program would be likely to hang ■ Sorted display of data segments and all allocated units ■ Assignment of allocation units to source file and line (when recompiling) ■ Optional selective display selection by specifying source file and line number ■ Viewing and editing of allocation unit contents ■ Possibility to set debugger breakpoints ■ Extensive setup options to tailor DMalloc's behaviour to the current debug context, and changing setup op- tions at runtime ■ Alternate monitor support to allow debugging of graphi- cal applications ■ User-defined screen colors on both monitors ■ Automatic save of setup options, and corrupted and se- lected allocation units on an per-application basis ■ Rich API for program/debugger interaction 1.5. What is Shareware Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and con- tinue to use it, you are expected to register. Copyright laws apply to both Shareware and commercial soft- ware, and the copyright holder retains all rights. Sharewa- re authors are accomplished programmers, just like commer- cial authors, and the programs are of comparable quality - in both cases, there are good programs and bad ones! The main difference between the two is in the method of distribution. ----- DMalloc ------------------------------------------- Page 2 of 52 ------ So Shareware is a distribution method, not a type of soft- ware. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Sha- reware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee - if you don't use the product, you don't pay for it. 1.6. DMalloc Unregistered Evaluation Version The unregistered version of DMalloc is fully functional. When a program linked with the unregistered version is starting and terminating, a window will pop up to remind you that you are using an unregistered copy. To make this reminder screen go away, hit any key. 1.7. Registration DMalloc is copyrighted Shareware, it is NOT PUBLIC DOMAIN, it is NOT FREE. If you find DMalloc of value and continue to use it after a thirty day evaluation period PLEASE regi- ster your copy of DMalloc. When you register you receive: ■ a serial number and license for one copy of DMalloc ■ a diskette with a registered copy of DMalloc ■ six months free support ■ any technical updates of DMalloc v 1.0 available at that time ■ a printed and bound manual ■ a configuration utility to modify the DMalloc library to your setup requirements (see appendix B, page 41) ■ free interim updates when available ■ version 2.0 at a greatly reduced fee ■ reduced registration fee (by 10.00 US$) of the Z/Install Installation program ■ a greater voice in suggesting future enhancements ■ the satisfaction of supporting the shareware concept If you have not previously registered, and after an evalua- tion of DMalloc you wish to register, or if you would just like a registered copy to be shipped out to you, the cost is: 41.00 US$ s/h 6.00 US$ ------------- 47.00 US$ To have an additional manual shipped, the cost is 11.00 US$ s/h 6.00 US$ ------------- 17.00 US$ ----- DMalloc ------------------------------------------- Page 3 of 52 ------ To register, or to order additional printed manuals, fill out the registration form (REGISTER.FRM, see section 2.4.1, page 8), add a check, made payable to Ernest Vogelsinger, or money order (if not registering with credit card), and send them in using one of three options: 1) By regular mail to: Ernest Vogelsinger Hietzinger Hauptstrasse 40 c A-1130 Vienna, Austria North America only: Ben Morris SpeedSoft Development 2232 Tashy Place V8N4R6 Victoria BC, Canada 2) By telephone or fax: if this is by VISA or MASTERCARD credit card, call Tel: (+43) 1 876 46 090 (international line) ORDERS ONLY! SUPPORT IS NOT AVAILABLE AT THAT NUMBER. Fax: (+43) 1 876 46 094 (international line) North America only: if you want to register by VISA credit card, or to upload the registration form to the BBS, call SpeedSoft Development, Ben Morris, at Voice (604) 472-0626 BBS (604) 477-5337 Modem settings: 8 Data, 1 Stop, No Parity Modem speed: up to 14.400 baud, v.32.bis, v.42.bis 3) By electronic mail: if this is by VISA or MASTERCARD credit card, you can forward the information directly to me by: Compuserve Mail at 100015,551 Internet 100015.551@compuserve.com MHS MAIL@CSERVE {100015,551} North America only: CompuServe Mail at 72361,1552 Internet 72361.1552@compuserve.com MHS MAILCSERVE {72361,1552} Check appendix D, page 43, for detailed information on how to send email to Compuserve, and on how to obtain a Compu- serve account. If registering with credit card your account will be char- ged in Austrian funds (Austrian Schillings = ATS). You will receive a confirmation by electronic mail or fax (if available) when your order is processed. ----- DMalloc ------------------------------------------- Page 4 of 52 ------ Currency exchange will vary, but at the time of this ver- sion's release 47.00 US$ was approximately: 47.00 US$ (41+6s/h)ATS 479.40 The registration fee licenses one copy of DMalloc for use on any one computer at any one time. You must treat this software just like a book. An example is that this softwa- re may be used by any number of people and may be freely moved from one computer location to another, as long as there is no possibility of it being used at one location while it's being used at another. Consider it like a book, a book cannot be read by two different people at the same time. For commercial users of DMalloc, site-license or multiple license discount arrangements may be made by contacting the author at the above address. If there is an unavoidable delay in registering, note that DMalloc will continue to work unchanged after the evalua- tion period. Under no circumstances will DMalloc do any mischief to those who dishonestly continue to use DMalloc without registering. 1.7.1. Registering Your Evaluation Copy DMalloc will be registered personally to you, i.e. your serial number and your name will be shown at the top of the screen (the Information Window, see section 5.3, page 22). When you send in your registration, you will be provided a registration number. You can use this registration number together with the serialization utility to immediately re- gister your DMalloc library and get rid of the shareware reminder screens (DMSerial program, see appendix A, page 40, for more information). 1.8. Distribution Policies DMalloc(tm) and its documentation are COPYRIGHTED, and are NOT PUBLIC DOMAIN. Anyone distributing DMalloc for any kind of direct fee must first contact me at the address above for authorization. Although authorization will generally be automatically granted to distributors recognized by ASP as adhering to its guidelines for shareware distributors ("associated ASP members"), notification is still required. The above restriction does not apply to the case of normal & usual connect charges on a BBS, where no other specific charge is made for obtaining a copy of DMalloc. BBS Sysops Please refer to the file SYSOP.DOC on the distribution disk, or the uploaded ZIP file. Catalog and Disk Vendors Please refer to the file VENDOR.DOC on the distribution disk. ----- DMalloc ------------------------------------------- Page 5 of 52 ------ Individual users are encouraged to pass the "Unregistered Evaluation Copy" of DMalloc along to their friends for eva- luation. When secondarily distributed, DMalloc must be in its origi- nal compressed form and accompanied by its full on-disk documentation and other information files. The distributed software and documentation may not have been modified in any way. No secondary distributor is authorized to accept registrations for DMalloc. Registration fees may only be sent directly to the author as outlined above in section 1.7, page 3. Note that the registration fee is exclusive of, and over and above any fees that may be charged by a secondary distribu- tor. 1.9. Association of Shareware Professionals Ombudsman The author is a member of the Association of Shareware Pro- fessionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resol- ve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to: ASP Ombudsman 545 Grover Road, Muskegon MI 49442 U.S.A. or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536 ----- DMalloc ------------------------------------------- Page 6 of 52 ------ 2. Installation 2.1. From a Compressed Archive If you received DMalloc as a compressed file (usually DML100.ZIP (3)), please unpack the compressed file using your favorite unzip utility. If you're using PKUnzip, type PKUNZIP DML100 [Enter] at the DOS command prompt. This will unpack the archive and create the files as they are on the distribution disk. You may unpack the archive either to a floppy disk, or directly to your hard disk. After unpacking, proceed as if you re- ceived a distribution disk. 2.2. From a Distribution Disk The distribution disk contains the following files: README | Information how to install DMalloc FILE_ID.DIZ | Information for automatic extraction | by BBS software PACKING.LST | All files on the distribution disk ASP.DOC | A notice about the ASP ombudsman INSTALL.EXE | The installation program (Z/Install) INSTALL.LIB | The installation archive Insert the distribution disk into any diskette drive (or switch to the directory you copied the files to), and enter INSTALL [Enter] This will start the installation program. Follow the in- structions of the installation program to install DMalloc to your system. 2.3. Checking the Completed Installation When the installation program finishes, you should have the following files: README | Please read this! PACKING.LST | A list of all files in the package DMALLOC.LIB | The actual DMalloc software DMLNONE.LIB | These files will be installed to the DMALLOC.OBJ | directory as specified in the DMALLOC7.OBJ | installation program DMALLOC.H | DMALLOC.BC | DMSERIAL.EXE | unregistered shareware version only | to serialize the library | after registration DMCONFIG.EXE | registered version only | to configure the library to | your needs ____________________ 3 The BBS distribution archive has been created using PKZip(tm). ----- DMalloc ------------------------------------------- Page 7 of 52 ------ DOC\WARRANTY.DOC | Important warranty information DOC\REGISTER.FRM | A form letter to register DMalloc DOC\DESCRIBE.DOC | A complete description of DMalloc DOC\HISTORY.DOC | DMalloc update history DOC\VENDOR.DOC | Important informations for | shareware vendors DOC\SYSOP.DOC | Important information for BBS sysops DOC\LASTINFO.DOC | Last minute information DOC\DMALLOC.DOC | This documentation in ASCII format DOC\SH-WARE.DOC | Information on shareware, and computer | viruses DOC\ASP.DOC | Information about the ASP, its policy, | and the ASP Ombudsman DOC\OMBUDSMN.DOC | The ASP Ombudsman statement DOC\PRESINFO | Press information DOC\VIRUS.DOC | registered version only | "Computer Virus Myths" | by Rob Rosenberger, Ross M. Greenberg SAMPLE\DEMO.BAT | Batch and text file to start the demo SAMPLE\DEMO.TXT | SAMPLE\DMLDEMO.EXE | Disk version only (no BBS) | Ready to run demo program SAMPLE\MODULE1.C | The demo program source files SAMPLE\MODULE2.C | SAMPLE\MODULE3.C | SAMPLE\DMLDEMO.TXT | SAMPLE\DEMO.H | SAMPLE\MAKEFILE | Make file for MSC 5.1 and 6+ SAMPLE\DMLDEMO.MAK | MSC 7 PWB project file SAMPLE\DMLDEMO.STS | MSC 7 PWB session settings SAMPLE\README | Instructions how to build the demo program 2.4. Documentation 2.4.1. Registration Form REGISTER.FRM is the registration form you may use to regi- ster DMalloc, or to request additional manuals. You may print it by typing: COPY REGISTER.FRM PRN [Enter] To register, or to order a printed manual just fill it in, and mail it (together with a check or money order) to the address shown on the form. For additional information on registering and the many benefits you'll receive, please refer to section 1.7, page 3. ----- DMalloc ------------------------------------------- Page 8 of 52 ------ 2.4.2. The Manual DMALLOC.DOC is the installation, demo program and reference documentation (this text). It contains no special format- ting commands, can be viewed with any DOS text file viewer or editor, and it should be printable on most any printer. To print, type at the DOS command line: COPY DMALLOC.DOC PRN [Enter] You should have at least 56 pages (4) of paper ready when printing the manual. The documentation file includes "box drawings", these use certain characters which may not be available on some printers. Generally such printers replace these special characters with italicised letters. If you are able to, choose the "IBM mode" on such a printer. Don't let the thickness of the documentation scare you. DMalloc is extremely easy to use. This manual will do its best to teach you how to use DMalloc to debug your program. 2.5. A Quick Start To quickly get an existing program running with DMalloc, relink the application together with the DMALLOC.OBJ (5) object file. The DMALLOC.LIB library must be either in the current directory or in one of the directories specified in the LIB environment variable. After linking, start the program as usual. DMalloc will pop up before the main() function is called to allow you to modify the setup options. Note: if an application is not compiled using the large memory model (compiler directive -AL), the linker will issue an error message and the program will not work. You must compile the application using the large memory model (6). ____________________ 4 The size of the ASCII file differs from the printed docu- mentation due to different fonts and formatting 5 See section 6.1.1, page 33, for using different compiler versions. For now, use DMALLOC.OBJ for MSC 5.1 and MSC 6+, and DMALLOC7.OBJ for MSC 7. 6 Future versions may support different memory models. ----- DMalloc ------------------------------------------- Page 9 of 52 ------ 2.6. Where to from here? If you have never used DMalloc before, I would suggest that you either run the demo program together with reading sec- tion 3, page 10. To compile the demo program please refer to section 3.1, page 12. If do not like a walkthrough approach to learning a program, please study the reference sections: Section 3 is the walkthrough demonstration. Section 4 describes dynamic memory, what may go wrong with it and what DMalloc does to catch tho- se bugs. Section 5 describes the windows that appear in DMal- loc, and the use of the function keys. Section 6 describes how to use DMalloc, and contains caveats with different compiler and linker versions. Section 7 is the reference section for the DMalloc API. 2.7. Support & Thanks Questions, comments, suggestions, and even thanks are all welcome. I am supporting this software via regular mail or fax, or alternatively (this is preferred) on CompuServe, either via electronic mail, or on the MSLANG forum, Micro- soft C (3) section. Via CompuServe: Address messages to my UserID 100015,551 through Compu- Serve MAIL (GO MAIL at any CompuServe "!" prompt), or leave a message for me in the CIS:MSLANG forum, Micro- soft C (3) section (GO MSLANG at any CompuServe "!" prompt). Via our Canadian support BBS: SpeedSoft BBS, Home of Z/Install, The Fine Installation Utility Modem settings: 8 Data, 1 Stop, No Parity Modem speed: up to 14.400 baud, v.32.bis, v.42.bis Call: (604) 477-5337 Via regular mail: Forward all support questions to Ernest Vogelsinger Hietzinger Hauptstrasse 40 c A-1130 Vienna, Austria Via fax: To send your questions, suggestions, etc, call (+43) 1 876 46 094 (international line) ----- DMalloc ------------------------------------------- Page 10 of 52 ----- For registered users, support is free for 6 (six) months from date of registration. Email and CompuServe forum sup- port continues to be free, whereas support via fax or regu- lar mail will be charged US$ 10.-- per case. If the support in question is of interest to all registered users, it will be not be charged. Improved or new versions will be announced on CompuServe on the MSLANG forum, Microsoft C (3) section, and on the SpeedSoft BBS (see above). Registered users will be automatically notified either via electronic mail, fax, or regular mail. My sincere thanks go out to all of those who have helped me to improve DMalloc by offering up their wish lists, sugge- stions and criticisms. Also a very special thanks to all the brave and tireless BETA/GAMMA testers. Enjoy! Ernest Vogelsinger ----- DMalloc ------------------------------------------- Page 11 of 52 ----- 3. The Demonstration Program The demonstration program consists of 3 files: DEMO.BAT | batch file to start the demo DEMO.TXT | text echoed by the batch file DMLDEMO.EXE | the actual demonstration program The demonstration program is a very simple C program that prints text to the screen, allocates some memory, and con- tains some nasty "bugs" to demonstrate the miscellaneous features of DMalloc. The source files for the demo are in- cluded as well: MODULE1.C | Main source file MODULE2.C | Additional modules MODULE3.C | DMLDEMO.TXT | Contains text printed on the screen MAKEFILE | MSC 5.1 makefile DMLDEMO.MAK | MSC 7 (PWB) project file DMLDEMO.STS | MSC 7 PWB session file 3.1. Compiling the Demo Program With MSC 5.1 and 6+, use the MAKEFILE make file to compile the demo program. Please make sure that DMALLOC.LIB and DMALLOC.H are either in the current directory, or available in the LIB and INCLUDE paths. With MSC 7 PWB, use the DMLDEMO.MAK project file to compile the demo project. For your convenience, the session set- tings file is included (DMLDEMO.STS). 3.2. Running the Demo The demo program is not intended to cover the complete functionality of DMalloc. It will give you an overview on the basic features, the windows, and the integrity checks. Note: your monitor should be in text mode, and the display width should be 80x25 or greater. If your primary display is smaller (e.g.40x25), or a graphics mode is active, DMalloc will either use an alternate monitor, if available, or immediately quit with an appropriate runtime error. To start the demo, type DEMO [Enter] Since DMalloc pops up just before the main() function is called (and before the demo can give you any explanation), there is a batch file to help you at the very start. If you typed DMLDEMO instead of DEMO, you are not really missing anything, except the batch file telling you to press [F5] to start the demo. ----- DMalloc ------------------------------------------- Page 12 of 52 ----- 3.3. DMalloc Startup Have a look at the screen now. On top you should see the Information Window. This window will always be visible whe- never DMalloc pops up. Its title shows the version and li- cense number of DMalloc. The contents will always reflect why DMalloc popped up - now it says that it's about to initialize. The Setup Window in the center of the screen can be used to modify the configuration options. For now we'll keep them as they are. On the bottom of the screen the function keys are display- ed. This line always reflects the actual status of the function keys - if there is no action for a key, it will be empty. The keys available now are [F2] Colors modify the window colors [F4] View temporarily hide the DMalloc windows and view the program screen [F5] Go! close all open windows and continue [F6] Select select the heap entries that will be displayed when the Heap Entries Window pops up [F10] Back close the topmost window and continue with the window below The [F5] and [F10] keys are always available. Remember, you are still before the execution of main() be- gins. To actually start the demo program press [F5] now. Now the demo program is allocating a bunch of memory. As in a "real-world" C program, different source modules issue calls to malloc(). Two of them have been compiled with DMalloc info enabled, and the third without (as third party code would generally be). While allocating, you will notice DMalloc popping up regularly to check the consistency of the heap. At any time you may use DMalloc to look at the heap. To interactively popup DMalloc, press [PrtSc]. 3.4. Heap Overview If you haven't already, Please press [PrtSc] now. As there is no heap problem the Information Window shows that you pressed [PrtSc]. Below you see the Heap Entries Window. That's the main window of DMalloc. The Heap Entries Window lists all memory units that have been allocated by the program (7), sorted by address. Use the [Up], [Down], [PgUp], [PgDn], [Home] and [End] keys to move through the list. Press [Enter] to view the contents ____________________ 7 except units allocated with halloc() since they are not part of the heap. ----- DMalloc ------------------------------------------- Page 13 of 52 ----- of a unit, or use the [F7] key to see the total heap status (see next section). If you are done, press [F5] to continue with the demo. 3.5. Total Heap Status Available at any time by pressing [F7], this window tells you the total amount of used and free memory, the size of the biggest available unit (very much like the _memmax() function), and the biggest unit available from DOS (i.e. memory that has not yet been claimed by the runtime library). 3.6. Detecting Heap Problems Please press [F5] now to continue. Now, the demo program will do some out-of-bound writes to the allocated units. What would happen in a "real-world" program cannot be predetermined since it depends very much on the actual memory layout at runtime, what the program would do next (regarding the heap), and much more. It could never cause any harm, it could destroy some data, it could hang the machine, or crash the operating system. With DMalloc checking the heap, these errors will immedia- tely be found. When DMalloc pops up you'll notice that the Information Window tells you that corrupted units have been detected. The bar in the Heap Entries Window will be positioned at the first corrupted unit. To quickly jump between corrupted units, use the [Left] and [Right] keys. Three types of problems are shown here: Trailing Corruption (the first unit): This is the most com- mon problem. It occurs whenever you write more to a unit than you have allocated. Under normal conditions (without DMalloc) this would overwrite the allocation info of the following unit. Odd/Even Corruption (the second unit): Although similar to the first case it would never cause any problem in a "real- world" program. When an odd-sized unit is allocated, the runtime library automatically expands the size by one byte to evenly align units. However, the unit size may have been calculated (e.g. using strlen()), and this one-byte over- write would cause a Trailing Corruption if the size was even! Leading Corruption (the third unit): This would destroy the allocation info of the unit itself. It may be caused by an overwrite of the preceding unit, or by a faulty negative- index calculation into the unit itself. Press [F5] to continue the demo when you're ready. ----- DMalloc ------------------------------------------- Page 14 of 52 ----- 3.7. Invalid Pointer Warning Whenever the program passes invalid parameters to free(), realloc() and expand() DMalloc will inform you. The reason for that kind of error may be either uninitialized varia- bles, duplicate freeing of the same pointer, freeing poin- ters to non-allocated data, and much more. Since the free() function doesn't check anything (except NULL pointers), and simply writes to the allocation info (immediately preceding the memory location pointed to) this could harm data needed elsewhere. 3.8. Determining Action, Setting Breakpoints Now press [F10] to step back to the Information Window. You'll notice two selection fields: "You can:" and "Break- point:". These selection fields are always present in the Information Window unless you have pressed [PrtSc]. Press [Space] to scroll the options, and press [Tab] or [Enter] to switch between the fields. The "You can:" field offers the following possibilities: Discard: since the pointer to be freed is invalid you may discard the call to free(). Exit program: this will immediately exit the debugged program by a call to exit(). Any function specified for atexit() or onexit() processing will be called. Continue: normally continue the program. Note: if you choose this option now, freeing the invalid pointer may hang your machine! The "Breakpoints:" field offers the following possibili- ties: None: no breakpoint will be set. SoftIce: DMalloc will generate a SoftIce breakpoint (see section 6.6.1, page 37). If you have SoftIce loaded, try this option now. CodeView: set a CodeView breakpoint. Int3: Set an unspecified interrupt-3 breakpoint. Interrupt 3 is generally used to set debugger breakpoints. The breakpoints will activate the debugger at the statement after the function that caused DMalloc to pop up. In as- sembler, you'll see a statement like "ADD SP, +2". In sour- ce mode, you'll see the line containing the function call. After making your selections, press [F5] or [F10] to conti- nue. ----- DMalloc ------------------------------------------- Page 15 of 52 ----- 3.9. Null Pointer Assignments DMalloc can check for null pointer assignments. The demo will now overwrite the first few bytes of the data segment. In a "real-world" program this would only be detected when the program finishes. DMalloc will detect it much earlier when it walks the heap. The same check is also available for far null pointers. Usually, far null assignments overwrite the interrupt ta- ble. When a far null assignment is detected, DMalloc will not only tell you, but also undo the changes! 3.10. Fatal Heap Errors Although DMalloc detects heap overwrites, it cannot guaran- tee that the allocation info needed by the runtime library is not tampered with. Whenever the heap structure is com- pletely destroyed (and a non-DMalloc program would hang), it will tell you so and gracefully exit the program. The demo program will now destroy the heap completely and start to free the pointers it previously allocated. Next time it gets a chance DMalloc will detect the heap failure and allow controlled program exit. ----- DMalloc ------------------------------------------- Page 16 of 52 ----- 4. Dynamic Memory and DMalloc 4.1. Dynamic Memory Layout The C Runtime Library allocates dynamic memory by partitio- ning the heap into allocation units. Each unit is preceded by an information block containing the size and the alloca- tion status (used/free): ───┐ ┌───────────┐ ┌─────────── ╦═╧═╧╤════════╦═╧═╧╤════════╦ ║Info│Contents║Info│Contents║ ╩════╧╤═══════╩════╧════════╩ └ malloc() pointer Since the allocation information is used to link the single units this is very critical to the integrity of the dynamic heap. Any tampering with the contents of the information field will produce unpredictable results. Even though most heap corruptions are only off-by-one errors, they can ne- vertheless be dangerous. 4.2. DMalloc and Dynamic Memory ───┐ ┌───────────────────┐ ┌─ ╦═╧═╧╤═══╤════════╤═══╦═╧═╧╤ ║Info│Dml│Contents│Dml║Info│ ╩════╧═══╧╤═══════╧═══╩════╧ └ malloc() pointer Here's where DMalloc comes in - it copes with heap problems is two ways: ■ it surrounds any allocated unit with small buffers con- taining initialized data to track those off-by-some errors, and to provide that they don't really corrupt the heap (allocation overhead = 2x4 bytes) ■ it tracks all allocated units in a tag table to hold additional information about the unit (one tag table entry = 10 bytes): ■ it provides the source file name and the line number where the unit has been allocated ■ it allows to "mark" any unit so freeing, reallocating and expanding will let DMalloc pop up ■ it checks the parameters for free(), realloc() and ex- pand() calls ----- DMalloc ------------------------------------------- Page 17 of 52 ----- 4.3. Tracking the Functions One of the most convenient features of DMalloc is that it automatically tracks calls to the malloc functions, even without recompiling the code. How does this work? On startup, before main() is called, DMalloc patches the entry points to the malloc functions. When they are called later, control will automatically be passed to the DMalloc code. The following functions will be tracked (8): ■ _fmalloc (this is where the malloc() label points to in the large memory model) ■ calloc ■ realloc ■ expand ■ _ffree (this is where the free() label points to in the large memory model ■ _nmalloc ■ _nfree These functions are referenced throughout the manual as "malloc functions". Calling one of them will automatically activate DMalloc. 4.4. Checking the Heap DMalloc checks the heap by calling the compiler specific heap walk functions for the near and far heap, and tests the results against its tag table. Whenever a corrupted unit is detected it will pop up. This heap walk can only be done when DMalloc gets control: ■ one of the above functions is called ■ each time DMalloc pops up ■ using the DMalloc programming API Usually it is not necessary to check the heap on every call to a malloc function. The frequency of the automatic check can be changed at runtime in the Setup Window (see section 5.4, page 19), or with the DMalloc API (see section 7, page 32). ____________________ 8 The tracked functions are compiler specific. These are the functions for MSC. See section 6.1.1, page 33 for informa- tion about compiler versions. ----- DMalloc ------------------------------------------- Page 18 of 52 ----- 4.5. Types of Heap Corruption A program can overwrite the allocation information fields in both directions: upwards, destroying the info field of successive ("trailing") units, or downwards, destroying its own ("leading") information field. DMalloc detects both kinds of errors. Refer also to section 5.6, page 27, Heap Entries Window. 4.5.1. Lead Corruption Lead Corruption occurs when the allocation information field preceding the unit is destroyed. This may be caused by either faulty downward indexing at the corrupted unit itself, or by out-of-bounds writes to the preceding unit. 4.5.2. Trail Corruption Trail corruption occurs when the allocation information field following the unit is destroyed. This is most likely caused by out-of-bounds writes to the unit. 4.5.3. Odd/Even Problem Odd/Even corruption is a special case of Trail corruption. Regardless if the allocated size is even or odd, the malloc functions always pad the unit size to be even (9). Thus writing one byte more than allocated would never cause a problem, and would never be detected. DMalloc however cat- ches this kind of problem as well, since the size could be a calculated value, and the off-by-one access would cause a Trail Corruption if the size was even. 4.5.4. Mavericks Mavericks are allocated units that DMalloc doesn't know about, but detects when walking the heap. Since there is no "legal" way of allocation bypassing DMalloc, the occurrance of Mavericks is a clear sign that stray pointers corrupted the heap. Mavericks will usually be found when DMalloc de- tects an unrecoverable heap failure, and thus would termi- nate the program. ____________________ 9 This grants all allocated units to be aligned at an even address. ----- DMalloc ------------------------------------------- Page 19 of 52 ----- 4.6. Null Pointer Assignments The C runtime library provides a way to detect Null pointer assignments at the end of the program. Since this is a bit late to tell where it could have happened, DMalloc checks the NULL region whenever it checks the heap (see section 5.6.3, page 25 how to activate this feature). It will pop up whenever it detects a change in the contents of the NULL region. Note: the runtime library provides 40h bytes at the beginning of the data segment to allow for checking against Null pointer assignments. You may disable this feature to save data and code space by providing a "int _nullcheck(void);" function returning 0 (10). In this case, the linker will not pull the constant NULL segment in, and DS:0 assignments are perfectly valid since it's the program's data. DMalloc is aware of this and disables the (near) Nullcheck feature. 4.7. Far Null Pointer Assignments Compiling for far data, NULL pointers will not point to the data segment NULL region but to the interrupt table. As- signments to FAR NULL pointers normally hang the machine, since interrupt pointers are destroyed. DMalloc checks the FAR NULL region (see section 5.6.3, page 29, how to activa- te this feature). Whenever an unknown change (11) is detected, DMalloc will reset the contents of the interrupt table to a known state, and pop up. Note: This is not a "lifebelt". Since an interrupt may be called before DMalloc detects the change, it may still crash the machine (12). 4.8. Watchpoints DMalloc provides a way to notify you whenever a specific allocation unit is to be reallocated, expanded, or freed. Marking an allocated unit (see section 5.6.3, page 29) sets a Watchpoint that will direct DMalloc to pop up whenever that unit is to be freed, expanded, or reallocated. 4.9. Savepoints DMalloc can remember certain allocated units from one ses- sion to the next, where it may pop up when a remembered unit has been allocated. This is automatically done with corrupted units. Additionally you may specify Savepoints (see section 5.6.4, page 30) to be saved for the next ses- sion, similar to a corrupted unit. When DMalloc pops up because a remembered unit has just been allocated, it will tell if it has been a corrupted or a saved entry. ____________________ 10 This function must reside in the _TEXT segment. The function name depends on the runtime library; this is what it's called in MSC. 11 DMalloc will know when the operating system changes an in- terrupt. 12 Interrupts called frequently are 08h and 1Ch (timer), 09h and 16h (keyboard), 10h (video), 21h (DOS), and some more. However, interrupts 00h to 07h (the first two paragraphs) are not frequently called. ----- DMalloc ------------------------------------------- Page 20 of 52 ----- 5. DMalloc In Detail Regardless of the situation, two elements of the user in- terface will always be present when DMalloc is up: the Function Key display, and the Information Window. 5.1. About DMalloc Windows DMalloc uses three window types: ■ Informational windows containing only text. You cannot scroll or modify data ■ Data entry windows. You may enter or modify data at various entry fields. ■ A Listbox-like window Three types of data entry fields are available: ■ Ascii data entry to enter text. ■ Numeric data entry to enter numeric values. You may use the [Space], [Plus], [Minus], or [Back] keys to let it count up or down. ■ Selection entry to select from certain available valu- es. Press the [Space] key, or the first letter of the selection of your choice (e.g. [C] to select "Conti- nue"). After entering or changing data in an data entry window, you may confirm the changes by pressing [F5] or [F10], or undo them by pressing [Esc]. 5.2. Function Keys The available function keys are always displayed at the bottom of the screen. Keys that are always available: [F4] View Hide the DMalloc screen to show the screen of the debugged program (if an alternate monitor is used (see section 5.4.8, page 25), this key is unavailable). [F5] Go! Close all open DMalloc windows (as if pressing [F10]) and immediately continue the interrupted program [F10] Back Close the topmost window and continue with the next below. If data has been entered in the active window, it is saved. [Esc] Undo Close the topmost window and continue with the next below. If data has been entered in the active window, changes are discarded. ----- DMalloc ------------------------------------------- Page 21 of 52 ----- Keys that open a window, or perform an action: [F2] Setup Window -> Colors Window [Shft]+[F2] Repair unit [Ctrl]+[F2] Repair all [F3] Heap Entries Window -> Dump Window -> Edit Contents [F6] Selection Window [F7] Heap Status Window [F9] Set/Clear Watchpoint [Space] Toggle Watchpoint [Ctrl]+[F9] Set Watchpoint at all visible units [Alt]+[F9] Toggle Watchpoint at all visible units [Shft]+[F9] Clear Watchpoints at all visible units 5.3. Information Window ╔╡ DMalloc 1.0 for MSC 5.1/6+ (c) 1990-1992 E.Vogelsinger (UNREGISTERED) ╞══╗ ║ DMalloc has detected a heap problem: ║ ║ One or more allocated units have been overwritten. ║ ║ You can: Continue Breakpoint: None 1 new heap problem ║ ╚═══════════════════════════════════════════════════════════════════════════╝ The title bar shows the DMalloc version, the compiler mo- del, and the serial number. The window text describes the exact reason for DMalloc to pop up. If a new heap corruption is detected (i.e. corrupted en- tries that have not yet been displayed), the total number of the new detections is displayed in the lower right cor- ner. Two selection fields are present at the bottom: 5.3.1. "You can" - Select the Next Action Continue will continue the debugged program. Exit program will exit the program as soon as you leave DMalloc. Discard action will discard the action that caused DMalloc to pop up. This choice is only available if ■ an invalid pointer was passed to realloc() or free() ■ a far pointer was passed to _nfree() ■ a Watchpoint has matured (see section 4.8, page 20) ----- DMalloc ------------------------------------------- Page 22 of 52 ----- 5.3.2. "Breakpoint:" This field can be used to set breakpoints to debuggers (see section 6.6, page 36). None will not set any breakpoint SoftIce generates a breakpoint for the Soft-ICE(tm) debugger CodeView generates a breakpoint for the CodeView(r) debugger Int3 generates an unspecified INT 03h instruction Note: Both selection fields are only present if DMalloc automatically popped up. Pressing the [PrtSc] key to activate DMalloc is an asynchronous action. The state of the operating system or a debugger cannot be predicted at this moment, so it could be fatal if DMalloc would try to break into the debugger, or to exit the running program. 5.4. Setup Window ╔╡ Setup ╞════════════════════╗ ║ ║ ║ Alert on problem : Yes ║ ║ Popup on saved : No ║ ║ Cycles for popup : 0 ║ ║ Heap check cycles: 100 ║ ║ Popup for file ║ ║ line : 0 ║ ║ Startup screen : Yes ║ ║ Shutdown screen : Yes ║ ║ Alternate monitor: No ║ ║ Number of handles: 5000 ║ ║ ║ ╚═════════════════════════════╝ The Setup Window allows to modify the behaviour of DMalloc at runtime. The Setup Window is always available by pres- sing [F2]. All setup options will be permanently stored in the confi- guration file (see section 5.10, page 32). 5.4.1. Alert on problem (Default: Yes) Specifies if DMalloc should pop up if heap corruption is detected. Entering "No" lets DMalloc keep quiet even if it detects newly corrupted allocation units. However, there are situations when DMalloc will pop up regardless of this switch: ■ DMalloc is about to initialize (except switched off, see section 5.4.6, page 24) ■ an unrecoverable heap failure has been detected ■ a unit that has been found corrupted during the last session has been allocated, and the "Popup on saved" switch (see section 5.4.2, page 24) is set to "Corrupt" or "Both" ■ a unit marked for save (see section 5.6.4, page 30) has been allocated, and the "Popup on saved" switch is set to "Saved" or "Both" ■ the popup cycle count has elapsed (see section 5.4.3, page 20) ----- DMalloc ------------------------------------------- Page 23 of 52 ----- ■ the source file/line specified as popup reason is exe- cuted (see section 5.4.5, page 24) ■ [PrtSc] has been pressed ■ the DML_Trigger() API function was executed (see sec- tion 7, page 32) ■ the program has finished, and DMalloc is about to shut- down (except switched off, see section 5.4.7, page 25) Regardless of this switch, a small "Please wait" sign will always pop up whenever DMalloc checks the heap. 5.4.2. Popup on saved (Default: No) DMalloc remembers units that have been found corrupted, and those marked for save (see section 5.6.4, page 30) during the last debug session. You may selectively specify which units you want to monitor: No disables this feature Corrupt will pop up only for units that have been corrupted in the last session Saved will pop up only for units marked for save in the last session Both will popup for both types. 5.4.3. Cycles for popup (Default: 0) Regardless of heap corruption, DMalloc can be directed to pop up after a certain number of calls to the malloc functions have been made. Specify 0 if you do not want cy- cled popup. Note: the internal cycle counter is reset to zero whenever DMalloc pops up. 5.4.4. Heap check cycles (Default: 100) Specifies after how many calls to the malloc functions DMalloc will check heap integrity. Although heap checking is quite fast, it is not necessary on every call. Specify 0 if you do not want any automatic checking. Note: the heap will be checked always before DMalloc pops up, regardless of this setting, or if an invalid parameter to realloc(), free(), or expand() is detected. 5.4.5. Popup for file/line (Default: blank/0) Entering a source file name will direct DMalloc to pop up whenever a call to the malloc functions is made by this source file. Entering a line number will further restrict popup to this specific source line, line number 0 will al- low popup at any call from this file. Note: the source file in question must be compiled with DMalloc information to enable this feature. If a wrong file name or a line number that does not contain a call to the malloc functions is entered, DMalloc will not pop up, even if the line is executed. 5.4.6. Startup screen (Default: Yes) Normally, DMalloc pops up at the beginning, just before calling main(). You may disable the Startup Window by spe- cifying "No". ----- DMalloc ------------------------------------------- Page 24 of 52 ----- 5.4.7. Shutdown screen (Default: Yes) Normally, DMalloc pops up at the end, after the atexit() or onexit() functions have been called. You may disable the Shutdown Window by specifying "No". 5.4.8. Alternate monitor (Default: No) You may use an alternate monitor for DMalloc by selecting "Yes". DMalloc will use the selected monitor when it pops up the next time. There are situations where DMalloc will use the alternate monitor regardless of this setting: ■ your program switched to graphics mode ■ your program switched to a text mode with a different horizontal or vertical resolution than at initializa- tion time If you do not have an alternate monitor, and DMalloc would require it, it will not pop up until the display is reset for DMalloc's needs. Note: if, at initialization time, the display is either in graphics mode, or the text mode resolution is below 80x25, DMalloc will exclusively use the alternate display. If, in that case, you do not have an alternate display, DMalloc will immediately terminate at startup, issuing an appropriate runtime error. Note: if you do not have an alternate monitor, or the the alternate monitor is exlusively used by DMalloc, this field will not be accessible. 5.4.9. Number of handles (Default: 5000, Maximum: 10900) As mentioned in section 4.2 (page 14), DMalloc allocates a tag table to track the allocated units. This entry speci- fies the size of the tag table. As this value is needed only at initialization time, this field is not accessible later. Note: If DMalloc runs out of handles (more allocations than table entries), it will abort the program and issue an appropriate runtime error. ----- DMalloc ------------------------------------------- Page 25 of 52 ----- 5.5. Colors Window ╔╡ Window Colors ╞═════════════════════╗ ║ ║ ║ Notice : 3E Frame 3F Contents ║ ║ Heap : 3E Frame 30 Contents ║ ║ Dump : 3E Frame 30 Contents ║ ║ Selection : 3E Frame 38 Contents ║ ║ Status : 3E Frame 31 Contents ║ ║ Color : 3E Frame 30 Contents ║ ║ Setup : 3E Frame 30 Contents ║ ║ Wait message : 3E Frame 30 Contents ║ ║ Function Keys: 70 Contents ║ ║ ║ ╚══════════════════════════════════════╝ The Colors Window allows to customize the screen colors of DMalloc. It is available only from the Setup Window by pressing [F2]. For each window there are two entries: for the window fra- me, and for the window contents (13). The fields are se- lection fields that can be scrolled by pressing the [Space], [Home], or [End] keys. To switch between the fields, press the [Enter] or the [Tab] key. DMalloc maintains two color tables, one for color and one for monochrome displays. The Colors Window will display the table for matching the active display type. The color options will be permanently stored in the confi- guration file (see section 5.10, page 32). After colors have been changed they will be reflected whenever a window comes "on top" again. ____________________ 13 Except for the function keys - they have no window frame. ----- DMalloc ------------------------------------------- Page 26 of 52 ----- 5.6. Heap Entries Window ╔╡ Heap entries ╞══════════════════════════════════════════════╗ ║▒Block▒▒▒▒▒▒▒▒▒▒▒▒▒▒Owner▒▒line▒▒▒▒Size▒▒▒▒▒▒▒Lead▒▒▒▒▒▒Trail▒║ ║ 44CA:B0FC module1.c 175 86 OK OK ║ ║ 44CA:B15C module2.c 24 77 OK OK ║ ║ 44CA:B1B4 52unknown 43 OK OK ║ ║▒44CA:B1EA▒▒▒▒▒▒module1.c▒▒▒175▒▒▒▒▒▒86▒▒▒▒▒▒▒▒▒OK▒▒CORRUPTED▒║ ║ 44CA:B24A module2.c 24 77 OK ODD-EVEN ║ ║ 44CA:B2A2 52unknown 43 OK OK ║ ║ 44CA:B2D8 module1.c 175 86 OK OK ║ ║ 44CA:B338 module2.c 24 77 OK OK ║ ║ 44CA:B390 52unknown 43 CORRUPTED OK ║ ║ 44CA:B3C6 module1.c 175 86 OK OK ║ ╚══════════════════════════════════════════════════════════════╝ The Heap Entries Window displays a list of all allocated units. Usually, the Heap Window is always visible (14). If not, you may activate it by pressing [F3]. You may scroll through the heap list using the [Up], [Down], [PgUp], [PgDn], [Home], and [End] keys. The current position in the list is marked by an inverted bar. Each line represents an allocated unit, or another part of the programs memory. As shown above, the display contains (from left to right) Block the (far) address of the allocated unit. This ad- dress was returned by the malloc functions. Owner the source file that allocated this unit. If the owning source has not been compiled with DMalloc information, "52unknown" is displayed. line the source line if the owner file is available. Size the allocated size in bytes. Lead the status of the leading control block (see section 4.2, page 14). Possible values are: OK the leading control block is OK CORRUPTED the leading control block has been overwritten Trail the status of the trailing control block (see section 4.2, page 14). Possible values are: OK the trailing control block is OK CORRUPTED the trailing control block has been overwritten ODD/EVEN an off-by-one error on an odd-sized unit has been detected (see section 3.6, page 12) ____________________ 14 Unless you stepped back to the Information Window by pressing [F10] ----- DMalloc ------------------------------------------- Page 27 of 52 ----- Other entries that may be visible belong to preallocated data space and the Far Null region: ║ 0000:0000 256 OK FAR_NULL ║ ║ 2975:0000 49984 OK FAR_DATA ║ ║ 35A9:0000 5040 OK FAR_BSS ║ ║ 36E4:0000 13990 OK _DATA ║ ║ 36E4:36A6 538 OK BSS ║ ║ 36E4:44B2 190 OK DMALLOC ║ ║ 46E5:0016 1048 OK STARTUP ║ FAR_NULL The first 256 bytes of the interrupt table. As a special feature for far pointers, DMalloc can track Far Null Pointer assignments (see section 4.7, page 16). To have Far Null checking enab- led, this entry must be "tagged" (see section 5.6.3, page 25). FAR_DATA All pre-initialized data that doesn't fit into the data segment. Listed for completeness. FAR_BSS All non-initialized data that doesn't fit into the data segment. Listed for completeness. _DATA The data segment containing pre-initialized data (15). DMalloc can track Null pointer assignments (see section 4.6, page 20). To have Null checking enables, this entry must be "tagged" (see section 5.6.3, page 29). BSS All non-initialized data belonging to the data segment. Listed for completeness (16). DMALLOC Memory allocated by DMalloc for its own purpose. They are used for screen buffers and the allocation tag table. STARTUP Not present with with all compilers. Some units may be allocated before DMalloc initializes. Usually they contain a copy of the environment, and a bunch of pointers. Listed for completeness. You may freely select which type of entries you want to see. Refer to section 5.7 (page 25), Selection Window. ____________________ 15 Actually the _DATA entry consists of four consecutive segments: NULL, _DATA, CONST, and MSG (MS-C). Since they all contain pre-initialized data they are gathered in this entry. They all belong to DGROUP and are addressed through the DS or SS register. 16 Since the BSS segment is part of DGROUP it has the same segment address as the _DATA entry. ----- DMalloc ------------------------------------------- Page 28 of 52 ----- 5.6.1. Detecting Corrupted Entries Whenever DMalloc detects a problem it will pop up. Regard- less of the popup reason displayed in the Information Wind- ow, the heap is completely checked, and the number of newly found corruptions blinks in the Information Window (see section 5.3, page 22). Corrupted Entries are always dis- played in high-intensity color (refer to section 4.5, page 19, for different corruption types). When they are considered new (17) they will blink. You can quickly move between corrupted entries by pressing the [Left] or [Right] keys. An allocation unit that has been found corrupted will al- ways be saved in the configuration file (see sections 5.10, page 28, and 5.4.2, page 20). 5.6.2. "Repairing" Corrupted Entries To clear the "corruption" marks at an entry, you can press [Shft]+[F2] to repair the currently active unit, or [Ctrl]+[F2] to repair all. Repairing units will reset the corruption flags, and also reset the contents of the surrounding control blocks (see section 4.2, page 17). Repairing NULLCHECK at the _DATA entry will not reset the contents of the Null region but only clear the corruption flag. Repairing NULLCHECK at the FAR_NULL entry will only clear the corruption flag. The contents of the Far Null region are automatically reset whenever this type of corruption is encountered. Note: when repairing a corrupted unit, DMalloc will reset the control block contents. If the program relies on these contents (outside of the allocated unit) don't repair but exit the program and correct the error. Note: Having repaired a unit, it will not be remembered (see section 5.10, page 32). 5.6.3. Watchpoints ("Tags") Watchpoints are used to activate DMalloc whenever a watched unit is to be freed, reallocated, or expanded (see section 4.8, page 17). Setting a Watchpoint on the FAR_NULL or _DA- TA segment will enable checking for Null pointer as- signments. Active Watchpoints are displayed as "Tags" () at the wat- ched entry. ____________________ 17 A heap corruption is considered new until it has been shown the first time. ----- DMalloc ------------------------------------------- Page 29 of 52 ----- You can quickly move between tagged entries by pressing the [Ctrl]+[Left] or [Ctrl]+[Right] keys. To set or clear Watchpoints, press [F9] or [T] to tag an entry [F9] or [U] to untag an entry [Space] to toggle one tag [Ctrl]+[F9] or [Ctrl]+[T] to tag all entries [Alt]+[F9] to toggle all tags [Shft]+[F9] or [Ctrl]+[U] to untag all entries 5.6.4. Savepoints DMalloc remembers allocation units between debug sessions (see section 4.9, page 20). This is done automatically for corrupted units. Optionally, you may specify some units to be saved by simply pressing [S]. Whenever DMalloc allocates a saved unit again it will pop up. Unlike remembering a corrupted unit, a Savepoint is sticky, i.e. you have to clear it by pressing [S] or it will be kept for that unit (as long as the unit keeps being allocated). Active Savepoints are displayed with an 'S' at the entry. 5.7. Selection Window ╔╡ Select ╞════════════════════════╗ ║ ║ ║ Allocated units : Yes ║ ║ Marked only : No ║ ║ Nullptr. areas : Yes ║ ║ Data segments : No ║ ║ System entries : No ║ ║ Owner file : ║ ║ line : 0 ║ ║ ║ ╚══════════════════════════════════╝ The Selection Window selects which entries will be display- ed in the Heap Entries Window. It is available only from the Heap Entries Window by pressing [F6]. Changing the se- lection will immediately be reflected by the Heap Entries Window. Allocated Units (Default: Yes) Selects all allocated units except those marked DMALLOC and STARTUP. Marked only (Default: No) If Yes, only entries that are currently tagged or mar- ked for save will be shown. Nullptr. areas (Default: Yes) If Yes, the FAR_NULL and _DATA entries will be shown. Data segments (Default: No) If Yes, all data segments (FAR_NULL, FAR_DATA, FAR_BSS, _DATA, BSS) will be shown. If No, the FAR_NULL and _DATA segments may be shown when "Nullptr areas" is "Yes". ----- DMalloc ------------------------------------------- Page 30 of 52 ----- System entries (Default: No) If Yes, DMALLOC and STARTUP entries will be shown. Owner file/line (Default: blank/0) If a source file is entered here, only those entries belonging to the specified source file/line will be shown. 5.8. Dump Window ╔╡ Dump 36E4:0000 ╞════════════════════════════════════════════════════════╗ ║ 36E40: 00 00 00 00 00 00 00 00-4D 53 20 52 75 6E 2D 54 ........MS Run-T ║ ║ 36E50: 69 6D 65 20 4C 69 62 72-61 72 79 20 2D 20 43 6F ime Library - Co ║ ║ 36E60: 70 79 72 69 67 68 74 20-28 63 29 20 31 39 39 30 pyright (c) 1990 ║ ║ 36E70: 2C 20 4D 69 63 72 6F 73-6F 66 74 20 43 6F 72 70 , Microsoft Corp ║ ║ 36E80: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 36E90: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ╚══════════════════════════════════════════════════════════════════════════╝ The Dump Window allows you to view and edit the contents of a memory unit. It is available from the Heap Entries Window by pressing [F3] or [Enter]. The Window Title displays the unit address. The contents are shown in hex and ASCII format. The column to the far left shows the (incrementing) 20-bit address (18). The size of the Dump Window may vary, depending on the ac- tual size of the memory unit. The maximum size (as shown above) is 16 paragraphs (or 256 bytes). If the size of the unit is bigger you may scroll the Dump Window using the [Up], [Down], [PgUp], [PgDn], [Home], and [End] keys. 5.8.1. Editing Data Press [F3] to edit the Dump Window contents. When in Edit mode, a block cursor appears at the location where data is to be modified. Using the [Tab] key you can toggle between Hex Mode and Ascii Mode. Use the [Up], [Down], [Left], [Right], [Home], and [End] keys to move the cursor. Modified data will be displayed in high intensity color. Pressing [F5] or [F10] will write the modified data back, pressing [Esc] will ignore the changes. Note: Edit Mode is not available at the memory units marked FAR_NULL and DMalloc, since their contents are critical to the system. Note: Modifying the _DATA unit between offset 00h and offset 40h will result in a NULLCHECK warning and the appropriate runtime error at program termination (Null pointer assignment). ____________________ 18 In Real Mode, the highest memory address available is FFFF:FFFF, or as absolute address 10FFEF. It needs 21 bits to form this number. However, this address should never be a malloc unit. ----- DMalloc ------------------------------------------- Page 31 of 52 ----- 5.9. Heap Status Window ╔╡ Heap Status ╞════════════════╗ ║ Blocks Bytes ║ ║────────────────────┬──────────║ ║ │ ║ ║ Allocated: 10 │ 170 ║ ║ Free : 2 │ 34384 ║ ║ biggest on heap │ 32776 ║ ║ biggest in DOS │ 212704 ║ ║ │ ║ ╚═══════════════════════════════╝ The Heap Status Window is available at any time by pressing [F7]. The following information is presented: Allocated the number of units currently allocated, and the memory size occupied by them. Free the number of free units currently available within near and far heap, and the total size of all free units. Note: DMalloc calculates neighboring free units as one. biggest on heap the size of the biggest free unit in bytes (19). biggest in DOS the biggest contiguous memory block currently available from DOS (20). 5.10. The Configuration File All options from the Setup, Colors, and Selection Window are permanently stored in a configuration file. The name of the configuration file will be the same name as the name of the debugged EXE file, with extension .DMC (21). If, by chance, there is another file with the same name, DMalloc will not attempt to read its contents at initialization time, and will not overwrite it when terminating. All allocated units that have been found corrupted are sto- red in the configuration file, even if they have been freed or reallocated again. Also units marked 'S' for save will be stored. DMalloc tries to be clever when storing pointers. Since the program can be loaded anywhere in memory the segment portion of pointers will not necessarily be the same the next time you run it. For this reason the segment portion of the pointer is somehow normalized. However, if the size of the data segments has changed, or the allocation sequence is different, there is no way for DMalloc to detect when saved pointers are allocated, since they may be located somewhere else. ____________________ 19 The similar _memmax() function reports on the near heap only. DMalloc reports on both near and far heap. 20 The total size of free memory may vary from the maximum size, depending on the respective environment. 21 For example, for a TEST.EXE program, DMalloc would create a TEST.DMC configuration file. ----- DMalloc ------------------------------------------- Page 32 of 52 ----- 5.10.1. Configuring the Library If you have the registered version of DMalloc you may use the DMConfig utility program to modify the Setup, Colors, and Selection settings in the DMalloc library directly. Please refer to appendix B, page 41, for information about DMConfig. 6. How to use DMalloc There are different levels of integration into the debugged program: ■ You may simply link DMalloc to the program, recompile part of, or all, source code. ■ Do the above -plus- call the DMalloc API functions from within the program. 6.1. Linking DMalloc to the Program This is the most simple way to integrate DMalloc. Relink the program with an additional object, DMALLOC.OBJ. You do not need to specify the DMALLOC.LIB library to the linker as long as it can be found in one of the directories specified in the LIB environment variable. This will integrate the whole DMalloc functionality except that DMalloc cannot know where units are allocated. 6.1.1. Using Different Compilers DMalloc is prepared to support different compilers and Run- time Libraries. The compiler and library specific data and code is located in the external object file you link with your program. Currently available are: MSC 5.1, 6+ DMALLOC.OBJ MSC 7 DMALLOC7.OBJ The Information Window will show for which compiler you have linked the program. Please make sure that you're al- ways using the correct object file. 6.1.2. Using Overlay Linkers You may use DMalloc with any overlay linker. However, there are a few precautions that must be kept in mind: ■ Always link the DMALLOC.OBJ file to the main program file. DMalloc cannot be overlaid. ■ If the linker allows to overlay runtime library functions, keep all functions of the malloc group within the main program. ----- DMalloc ------------------------------------------- Page 33 of 52 ----- 6.2. Recompiling If you want to know which source file allocated which units, you may recompile the source files where the malloc functions are called. First, define the _DMALLOC switch. You may either add -D_DMALLOC to the compiler directive in the make file, or add the line #define _DMALLOC to the source file. Next, include DMALLOC.H into the source by adding the fol- lowing line to the source file: #include <DMALLOC.H> Third, recompile the source, and link the program as speci- fied above. You still need DMALLOC.OBJ to be linked to the program. Note: DMALLOC.H must be included after the standard C include files (STDDEF.H, STDLIB.H). Note: The switch _DMALLOC needs to be defined before DMALLOC.H is included. 6.2.1. Effects and Side-Effects when using the _DMALLOC switch When you activate the _DMALLOC switch as outlined above, some sections in the DMALLOC.H include file are activated. This is what will happen: ■ Access to the API is granted. If the switch is undefi- ned all references to DMalloc API functions are resol- ved with empty statements. ■ The malloc group functions are redefined to point to DMalloc's function replacements (22). Each time you call a malloc function, the file name and line number information will be inserted into the code. Inserting the file name information is done by using the __FILE__ macro (this is how it is called with MSC). Unfor- tunately this will increase the size of the EXE file since it adds the complete file name each time you use it. ____________________ 22 Actually the functions are not replacements but prefixes that call the original runtime library functions later. ----- DMalloc ------------------------------------------- Page 34 of 52 ----- There is a workaround you may use to keep the compiler from adding the file name multiple times: #define _DMALLOC /* activate the DMalloc API */ #define __DMFILE__ /* define to use the single */ static char * DM_file$ = __FILE__; /* file name char constant */ #include <dmalloc.h> /* include the file */ By defining the __DMFILE__ switch the include file will use the static (23) character constant DM_file$ instead of repeatedly placing the __FILE__ macro. Due to the nature of the __FILE__ macro you cannot put the- se statements into an include file. It would always retrie- ve the name of the include file, not of the source file. 6.3. Calling the DMalloc API DMalloc provides API functions that can be called from the program (see section 7, page 38). The API functions allow to let DMalloc check the heap, popup DMalloc, temporarily or permanently modify the setup, set watchpoints or save- points on pointers, generate debugger breakpoints, and to disable or enable DMalloc for special purposes. Please see the API reference for detailed discussion. 6.4. DMalloc and Spawn All exec.., spawn... and system() calls can be used together with DMalloc. Dmalloc will automatically detect when another process is being executed, and disable itself. 6.5. DMalloc and Video DMalloc is compatible with the RLSI (Relocatable Screen Interface) specification. If you have installed a DOS memo- ry manager (e.g. DesqView(r), or Memory Commander(r)) that relocates the video buffer, DMalloc will continue to work. Note: If your program accesses the video buffer directly, it also needs to adhere to the RLSI standard, since the RLSI host will not trap and relocate "standard" video buffer accesses after RLSI has been initialized. Please read the next two sections about the RLSI specification. ____________________ 23 Do not forget to make that variable static! Otherwise you would only have one global symbol in the EXE file, and only see the name of the last linked object file, since the linker will treat it as a common variable. ----- DMalloc ------------------------------------------- Page 35 of 52 ----- 6.5.1. The Relocatable Screen Interface (RLSI) Some memory managers (e.g. Memory Commander(r)), or multi- tasking programs (e.g. DesqView(r)), relocate (parts of) the video memory to make more memory available to DOS. Pro- grams that use the default video frames (0xB800 for color, and 0xB000 for monochrome) for direct video writes will still work with these environments but will run a lot slo- wer than necessary, since the RLSI host must use an excep- tion mechanism to transfer the video access. Any program that uses direct video I/O should therefore call the RLSI interface before the first video access. The interface function is entered with a far pointer to the assumed video buffer (usually 0xB800:0 or 0xB000:0), and will return a valid far pointer to the relocated memory location. Additionally, calling the interface function will speed up video I/O, since the RLSI host assumes that the client knows about the relocation, and will not trap the old video locations. The shortcoming is: if you once call RLSI, direct I/O to the old video buffer will no longer be visible. You must use the pointer returned by RLSI. 6.5.2. Calling RLSI RLSI is called via interrupt 10h (video interrupt). union REGS regs; struct SREGS sregs; regs.x.ax = 0xFE00; /* RLSI function code */ regs.x.di = ofsVPage; /* video page offset, usually 0 */ sregs.es = segVBuffer; /* video buffer */ /* (usually 0xB800 or 0xB000) */ int86x(0x10, ®s, ®s, &sregs); ofsVPage = regs.x.di; /* get the RLSI values */ segVBuffer = sregs.es; 6.6. DMalloc and Debuggers DMalloc allows you to set debugger breakpoints. Whenever DMalloc pops up (except when [PrtSc] has been pressed) you may direct it to set a debugger breakpoint (see section 5.3.2, 19). The debugger will receive control at the statement im- mediately following the call to the malloc function (i.e. in your code instead of code belonging to the runtime library, or DMalloc). ----- DMalloc ------------------------------------------- Page 36 of 52 ----- 6.6.1. Soft-ICE(tm) Soft-ICE is a resident protected-mode debugger from Nu-Mega Technologies, Inc. It can be used to debug operating system code, high frequent interrupt code, TSR programs, and much more. Soft-ICE breakpoints are sticky. When Soft-ICE gets control you will see a message like this: Breakpoint generated by DMalloc (remove with BC 0) If you do not clear that breakpoint, Soft-ICE will always pop up at the very same location. Note: It will do no harm trying to set a Soft-ICE break- point without having Soft-ICE loaded. 6.6.2. CodeView(r) Contrary to a Soft-ICE breakpoint, CodeView breakpoints are not sticky. CodeView will get control at the statement af- ter the malloc function call, but no permanent breakpoint will be set. Note: It will do no harm trying to set a CodeView break- point without running CodeView. 6.6.3. Other Debuggers Every debugger will get control when interrupt 03h is exe- cuted. DMalloc provides that unspecific method for other debuggers. Note: Most CodeView versions will also get control at this type of breakpoint, Soft-ICE will not by de- fault. 6.7. DMalloc and Bounds-Checker(r) Bounds-Checker is a 386-based utility to detect out-of- bounds memory accesses while running a DOS program. It gi- ves the same type of memory protection as a protected mode operating system. DMalloc and Bounds-Checker are ideal com- panions. You can use Bounds-Checker to verify segment-based integrity, and DMalloc to assure the integrity of the heap contents. Bounds-Checker can be directed to allow access to memory locations that are protected by default (24) by specifying exceptions in an exception file. Since DMalloc accesses some restricted locations, Bounds-Checker must know about it or it would complain. An exception file for Bounds- Checker comes with the DMalloc package (DMALLOC.BC). Simply copy the contents of this file to your exception file, and Bounds-Checker will accept the liberties DMalloc takes. ____________________ 24 Typical candidates for exceptions are the code segment for routines written in assembler, the Bios area beginning at segment 40h, or the video memory. ----- DMalloc ------------------------------------------- Page 37 of 52 ----- 6.7.1. DMalloc and atexit() processing DMalloc keeps monitoring the heap during atexit() or one- xit() processing. If there is any problem with the heap during that phase that causes DMalloc to pop up, you will see a blinking "atexit() processing" sign in the top right corner of the Information Window. This is also valid if you exit the program by selecting the "Exit Program" option from DMalloc (see section 5.3.1, page 18). 7. The Programming API The DMalloc API functions are defined and prototyped in the DMALLOC.H include file. If "_DMALLOC" is defined, the functions will be accessed. If "_DMALLOC" is undefined, all API functions are defined as "empty statements" so the source file will compile without errors. 7.1. Activating the API At the top of each source file you want to compile with DMalloc information enabled, enter the following: #define _DMALLOC #include <dmalloc.h> Alternatively you could use the compiler switch -D_DMALLOC to enable the DMalloc API. Note: The file <dmalloc.h> must be included after any standard C include file (STDDEF.H, STDLIB.H). 7.2. Removing the API Calls You can remove the DMalloc code from the program without recompiling by replacing the DMALLOC.LIB library with DMLNONE.LIB. This library provides dummy entries for all functions, and reroutes the DMalloc malloc function calls to the runtime library. Note: You must not link the DMALLOC.OBJ file to the program when linking with the DMLNONE.LIB library. ----- DMalloc ------------------------------------------- Page 38 of 52 ----- 8. API Reference The following is the detailed reference for the DMalloc API calls. Please note that you must compile the source with DMalloc code enabled ("_DMALLOC" defined) in order to use the API. void pascal DML_Trigger (void) Purpose: Directs DMalloc to pop up. Parameters: none Return: void Remarks: Actually this is a macro calling DM_Trigger$(__FILE__, __LINE__). unsigned pascal DML_Check (void) Purpose: Directs DMalloc to check the heap. However, DMalloc will not pop up if a problem has been found. Parameters: none Return: A nonzero value indicates that a new heap problem has been detected. You may use the DML_Trigger() macro to pop up in that case. A zero value indicates no new problems found. DML_CheckPop(void) Purpose: Combines DML_Check() and DML_Trigger(). DMalloc will check the heap and pop up if any problems are found, regardless of the setting in the Setup Window (see section 5.4.1, page 23). Parameters: none Return: void Remarks: Implemented as a macro. ----- DMalloc ------------------------------------------- Page 39 of 52 ----- void pascal DML_Setup (fAlert, fSaved, usPopCycles, usCheckCycles, pszOwner, usLine) Purpose: Modifies switches from the Setup Window (see section 5.4, page 23). Parameters: unsigned fAlert SET_ON "Yes" SET_OFF "No" SET_UNCHANGED keep current value unsigned fSaved SET_CORRUPTED "Corrupted" SET_SAVED "Saved" SET_BOTH "Both" SET_OFF "No" SET_UNCHANGED keep current value unsigned usPopCycles number DMalloc pops up regularly after this number of calls SET_UNCHANGED keep current value unsigned usCheckCycles number DMalloc checks the heap after this number of calls SET_UNCHANGED keep current value char *pszOwner char * DMalloc pops up whenever this file calls the malloc functions PSZ_UNCHANGED keep current value. unsigned usLine number narrows popup for a source file to this source line SET_UNCHANGED keep current value Return: void void pascal DML_Select (fMalloc, fMarked, fNull, fData, fSystem, pszOwner, usLine) Purpose: modifies switches from the Selection Window (see section 5.7, page 30). For each logical switch you may specify either SET_ON, SET_OFF, or SET_UNCHANGED. Parameters: unsigned fMalloc show allocated units unsigned fMarked show only marked units unsigned fNull show both NULL segment entries unsigned fData show the data segment entries unsigned fSystem show the system entries unsigned pszOwner show only entries owned by that source file PSZ_UNCHANGED keep current value unsigned usLine number narrows the source file range to this source line SET_UNCHANGED keep current value Return: void ----- DMalloc ------------------------------------------- Page 40 of 52 ----- void pascal DML_SaveState (pSaveBuffer) Purpose: Save the current DMalloc state to a save buffer. Parameters: void *pSaveBuffer Pointer to the buffer where the DMalloc setup is to be stored Return: void Remarks: The setup contains all switch settings from the Setup Window, the Selection Window, and the Colors Window. You may use the handy DML_SAVEAREA macro to define a local (or global) variable. If you are allocating a save buffer be sure to provide at least DML_SAVESIZE bytes. void pascal DML_RestoreState (pSaveBuffer) Purpose: Restore a previously saved DMalloc state. Parameters: void *pSaveBuffer Pointer to the buffer where the DMalloc setup is to be restored from Return: void Remarks: The setup contains all switch settings from the Setup Window, the Selection Window, and the Colors Window. You may use the handy DML_SAVEAREA macro to define a local (or global) variable. If you are allocating a save buffer be sure to provide at least DML_SAVESIZE bytes. There is no error correction. You must not use a buffer that has not been previously filled by the DML_SaveState() function. unsigned pascal DML_Watchpoint (pUnit, fOnOff) Purpose: Set or clear a Watchpoint Parameters: void *pUnit pointer Pointer to an allocated unit FAR_NULLCHECK (un)tag the FAR_NULL unit DATA_NULLCHECK (un)tag the _DATA unit unsigned fOnOff SET_ON set a Watchpoint SET_OFF remove a Watchpoint SET_UNCHANGED keep Watchpoint status Return: A nonzero value indicates that the Watchpoint has been set or cleared. A zero value indicates that the pointer passed to that function could not be found in DMalloc's tag table. Specifying SET_UNCHANGED may be used to verify if the pointer has been allocated by the malloc functions. Note: without the _DMALLOC switch defined, this function will always return nonzero. ----- DMalloc ------------------------------------------- Page 41 of 52 ----- unsigned pascal DML_Savepoint (pUnit, fOnOff) Purpose: Set or clear a Savepoint Parameters: void *pUnit pointer Pointer to an allocated unit unsigned fOnOff SET_ON set a Savepoint SET_OFF remove a Savepoint SET_UNCHANGED keep Savepoint status Return: A nonzero value indicates that the Savepoint has been set or cleared. A zero value indicates that the pointer passed to that function could not be found in DMalloc's tag table. Specifying SET_UNCHANGED may be used to verify if the pointer has been allocated by the malloc functions. Note: without the _DMALLOC switch defined, this function will always return nonzero. void pascal DML_Breakpoint (fType) Purpose: Trigger a debugger breakpoint Parameters: unsigned fType BPT_SOFTICE set a Soft-ICE breakpoint BPT_CODEVIEW set a CodeView breakpoint BPT_INT3 set a generic Int03 breakpoint Return: void Remarks: The debugger will get control at the statement following the call to DML_Breakpoint(). void pascal DML_Disable (void) Purpose: Completely disables DMalloc Parameters: none Return: void Remarks: Normally this function need not be called. It completely disables DMalloc, and after re-enabling it, any memory unit allocated in the meantime will show up as MAVERICK error, since DMalloc didn't know about it. Note: Disabling increments a counter, thus, multiple calls to DML_Enable (see below) are required to re-enable DMalloc. void pascal DML_Enable (void) Purpose: Enables DMalloc after disabling Parameters: none Return: void Remarks: Enable DMalloc. Since DMalloc is enabled at the beginning, this function is only necessary after calling DML_Disable. ----- DMalloc ------------------------------------------- Page 42 of 52 ----- 9. Problem Solving, and Frequently Asked Questions Q: When I'm pressing the [PrtSc] key, DMalloc doesn't pop up, but something else happens. A: Three reasons are possible: ■ Your keyboard doesn't have a single [PrtSc] key. Try the [Shft]+[PrtSc] keys together. ■ Your program redirected interrupt 05h (the print- screen interrupt) for its own use. If this is the case, you cannot interactively popup DMalloc. DMal- locs heap cheker functionality will still be kept, and it will pop up whenever necessary. You may force DMalloc to pop up regularly by selec- ting a popup cycle count in the setup window (see section 5.4.3, page 24). ■ Some resident program is repeatedly changing inter- rupt 05h ([PrtSc] interrupt). Known programs are Pizzaz Plus, and HiJaak. Either unload these pro- grams, or modify their setup, if possible (e.g. HiJaak can be set to "semi-active"). Q: When I start the program, DMalloc doesn't come up with the Setup Window. A: In the Setup Window, you have specified "No" at the "Startup Screen" entry. Either change this to "Yes", or simply delete the configuration file to restore the default setup. Q: Whenever I run the program, DMalloc repeatedly pops up and shows an overwrite to the FARNULL region. A: Some resident program is repeatedly changing interrupts that have been routed to your program. Interrupts used by the C runtime library and DMalloc are: ■ Int 00h - division by zero (runtime library) ■ Int 05h - print screen handler (DMalloc) ■ Int 16h - keyboard interrupt (DMalloc) ■ Int 21h - DOS OS entry (DMalloc) ■ Int 23h - Ctrl-C and Ctrl-Break handler (runtime library and DMalloc) Some resident programs hook one or more of these inter- rupts, and, using the timer tick, repeatedly reset them, bypassing the operating system. Known examples are Pizzaz Plus and HiJaak. Having loaded these programs, untag the topmost (FAR- NULL) entry in the Heap Window. This will disable checking of the FARNULL region. Q: After an unrecoverable heap failure, the configuration file doesn't contain the corrupted pointers, only those I specified to "Save". A: This is perfectly normal. Usually, when an unrecover- able heap error is encountered, you will notice a lot of different problems like overwritten pointers, and Maverick entries. To avoid confusion during the next session, DMalloc skips the corrupted pointers in that case, and only saves those specified for "Save". ----- DMalloc ------------------------------------------- Page 43 of 52 ----- Q: The manual states that the configuration file name would be the same as the program name. Why is mine na- med "_DMALLOC.DMC" ? A: DMalloc uses the environment information to retrieve the program name. If either your operating system do- esn't provide this information (DOS <3.0), or your pro- gram releases the environment for memory's sake, DMal- loc uses this name as a last resort. Q: I had corrupted pointers, but DMalloc didn't remind me on the next session, even with the correct setup. A: To have this feature work reliably, there are two things that must be kept in mind: ■ The environment settings, and the program parame- ters, should be the same. This is because the MSC startup code allocates some memory for these valu- es, and if the sizes of these units differ, so may the location of successively allocated units. ■ The size of the data segments should not change. If you have recompiled with somewhat modified code, this feature is most likely to fail. ■ It is absolutely necessary to do the same things you did in the last session, and in the same se- quence. If you're calling the malloc functions in different order, or with different parameters, the layout of the dynamic heap will be different, and the pointers will be different, too. Q: I want to have NULLCHECK enabled, but DMalloc wouldn't let me tag the _DATA segment entry. A: It is possible to disable the runtime library NULL check. If you provide a module containing a "_nullcheck()" (25) routine at link time, the linker will take this module instead of the one provided by the runtime library. Your _nullcheck() function must reside in the _TEXT segment and must return (int)0. In this case the linker will not link the NULL segment that normally makes up the first 4 paragraphs of the data segment. As the contents of these paragraphs are data of your program and no constant value anymore, Null Pointer assignments are perfectly valid. DMalloc is aware of this, and will not do Nullchecks on a non-constant data segment. Q: I am using Bounds-Checker(tm), and so far my code seems to be clean. Now, having linked my program with DMal- loc, Bounds-Checker constantly pops up and complains. A: You need to tell Bounds-Checker the exceptions needed for DMalloc. A file named DMALLOC.BC should be on the DMalloc original disk. Copy the contents of this file to your exception file, and Bounds-Checker should not complain any more. ____________________ 25 The actual name depends on the runtime library; this is what it's called in MSC. ----- DMalloc ------------------------------------------- Page 44 of 52 ----- Q: Under DesqView, my program used to work. Now, having linked with DMalloc, I can see DMalloc's output, but my program's windows are gone! A: DMalloc uses RLSI (Relocatable Screen Interface) for direct video access. Normally, if your program writes to the screen buffer directly, an RLSI host (as DV) would normally trap and relocate your memory access - your program is slower. Using RLSI, you'll get the ac- tual address of your video buffer. However, after RLSI has initialized, "standard" video accesses are not trapped anymore. Thus, your program writes to "nowhe- re". Refer to section 6.5.2 (page 31) on how to call the RLSI host. Q: May I use DMalloc to debug a Windows program? A: No, sorry. DMalloc cannot be used for a Windows pro- gram. You may use DMalloc for any DOS mode program, even if you're running it in a DOS window. ----- DMalloc ------------------------------------------- Page 45 of 52 ----- Appendix A - The Library Serialization Program DMSerial The unregistered shareware version of DMalloc contains a utili- ty program that will serialize the shareware version of DMalloc after you sent in your registration. Together with the confirmation of your registration you will receive a personal serialization code. Together with that code, and your name, you may use the DMSerial program to remove the shareware reminder screens from the DMalloc library. To serialize the library, switch to the directory where you installed DMalloc to, and type DMSERIAL [Enter] at the DOS command prompt. DMSerial will respond with a short explanation and ask Please enter the directory of DMALLOC.LIB, or press ^C to quit: Now enter the directory of the DMalloc library. Note that you must enter a directory. So if the library is in the current directory, you must enter "." to specify the current directory. Do not enter a filename! If DMSerial finds the DMalloc shareware library, it prompts Please enter the user name (case sensitive!!), or press ^C to quit: Enter the name you specified as the user name in the registra- tion form. Take care that you write the name exactly as speci- fied. The serialization program is case sensitive at this point. At the very last you are prompted to enter the serialization code: Please enter the serializer code (10 char), or press ^C to quit: (Enter the 10-digit serialization code you have been provided with.) Your DMalloc (shareware) library is now serialized, and you won't be bothered by the shareware reminder screens anymore. You may now use the LIB program to remove the shareware notice from the library, by typing LIB DMALLOC -DM_SWARE; [Enter] at the DOS prompt. This will remove the object file containing the notification texts from the library. If you don't want to do that, you may use the /NOE switch on the linker's command line to avoid linking the text to your programs. Please do not distribute the serialized DMalloc library. Thank you. ----- DMalloc ------------------------------------------- Page 46 of 52 ----- Appendix B - The Library Configuration Program DMConfig Registered users of DMalloc will receive a library configura- tion program. As outlined in the manual (section 5.10, page 28), DMalloc saves all configuration information, such as setup information, colors, and display selection, to a configuration file. Using the DMConfig configuration program you may tailor the library defaults directly to your specific needs, or create a sample .DMC configuration file that you can use. To execute DMConfig, type DMCONFIG [filename] [Enter] at the DOS command prompt. The optional filename parameter can be either the name of an existing .DMC configuration file, or the name of the DMalloc library (including complete drive:\path specification). DMConfig will detect the type of file you spe- cified. If you specify a non-existing file, DMConfig assumes that you want to create a .DMC configuration file with that name. DMConfig uses the same user interface as DMalloc. Available windows are: ■ Setup ■ Colors ■ Select ■ Information The Information Window allows you to choose between the follo- wing actions: ■ Ignore and Exit Do nothing - simply exit the configuration program. This is the default if you didn't specify a filename on the command line. ■ Write to library DMALLOC.LIB Write the configuration information to the library. This is the default if you specified a library filename on the command line. ■ Create DMALLOC.DMC Create a (or write to an existing) configuration file. This is the default if you specified a configuration filename on the command line. ----- DMalloc ------------------------------------------- Page 47 of 52 ----- Appendix C - The Legal Department (License Agreement) Shareware distribution gives users a chance to try software before buying it. If you try a shareware program and continue using it, you are expected to register. Individual programs may differ on details - some request registration while others require it, some specify a maximum trial period. Registration often entitles the user for updates, printed documentation, or other "perks". Copyright laws apply to both shareware and commercial software, and the copyright holder may retain all rights. The only meaningful difference between shareware and commercial software is in the method of distribution. Shareware authors specifically grant the rights to copy and distribute the (unregistered) software/documentation, either to all and sundry or with specific restrictions. You should find software that suits your needs and bank account, whether it's commercial or shareware. Both types have good programs and bad, but shareware makes finding the right program easier, because you can try before you buy. Also, because distribution overhead is much lower, shareware prices are often lower, too. Finally, shareware has the ultimate money-back guarantee - if you don't use it, you don't pay for it. For this agreement, the term "DMalloc" refers to the DMalloc library and include file (DMALLOC.LIB, DMLNONE.LIB and DMALLOC.H), the demonstration program (DEMO.BAT, DEMO.TXT, and DMLDEMO.EXE) together with its accompanying documentation (DMALLOC.DOC). A G R E E M E N T DMalloc is "shareware" and is licensed at no charge to the user for evaluation. Feel free to share it, but you may not alter the program or documentation nor include DMalloc as part of another system. If you find this library useful and continue to use DMalloc after a 30 day trial period, you must make a registration payment to Ernest Vogelsinger. The registration fee will license one copy for use on one computer at any one time. For commercial users of DMalloc, and for those who want to include DMalloc within a beta-version of a program, very attractive site-license agreements may be obtained from Ernest Vogelsinger. Anyone distributing DMalloc for remuneration of any sort must first obtain authorization from Ernest Vogelsinger. Such authorization will automatically be granted to distributors recognized by the (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering DMalloc immediately. In either case, Ernest Vogelsinger must be advised. You are encouraged to pass a copy of the unregistered DMalloc library, demo program, and documentation along to your friends and colleagues for evaluation. Please encourage them to register too. All registered users receive the many benefits described in section 1.7, page 3. ----- DMalloc ------------------------------------------- Page 48 of 52 ----- Appendix D - How to Send Email to Compuserve The following information was put together by CompuServe's Feedback team in a response time of less than 12 hours to my inquiry. A very big thanks to all those people doing a wonder- ful job! D.1 How to obtain a CompuServe Account DMalloc is also supported via CompuServe, either on the CIS:MSLANG forum, Microsoft C (3) section, or via CompuSer- ve Mail (26). If do not have a CompuServe account, and want to obtain one, please contact CompuServe Customer Service 800-848-8990 or (614) 457-8650 To reach the MSLANG forum, type GO MSLANG at any CompuServe "!" prompt. To send a message follow the instructions of the forum software. Remember to post messages regarding DMalloc to section 3 (Microsoft C). To send email, type GO MAIL at any CompuServe "!" prompt. Follow the instructions from CompuServe. If you want to register DMalloc, send a note to 100015,551, stating your will to register, your Visa number, and that you agree to pay with your Visa account. If you have an account on a different network it is likely that you are able to send email to CompuServe. For some systems here's how to send email to CompuServe: D.2 MCI ■ At MCI Mail's "Command:" prompt, type CREATE and press the [Enter] key. ■ At the "TO:" prompt, type my name, press [Space], type EMS within parenthesis and press the [Enter] key. For example: TO: Ernest Vogelsinger (EMS) [Enter] ■ At the "EMS:" prompt, type COMPUSERVE and press the [Enter] key. For example: EMS: COMPUSERVE [Enter] MCI Mail responds by displaying EMS281-6320 COMPUSERVE. ■ At the "MBX:" prompt, type my CompuServe User ID number and press [Enter] : MBX: 100015,551 [Enter] ■ At the second "MBX:" prompt, press [Enter]. ____________________ 26 Formerly "Easyplex" ----- DMalloc ------------------------------------------- Page 49 of 52 ----- ■ The information that you have entered is displayed for your approval. You should type YES if correct or type NO if there is an error and press [Enter]. For example: TO: Ernest Vogelsinger EMS: COMPUSERVE/ MCI ID: 281-6320 MBX: 100015,551 Is this address correct (Yes or No)? YES [Enter] ■ At the next two prompts, "TO:" and "CC:", press [Enter] to skip them. ■ Now type your message and send it as any MCI Mail mes- sage. When unsure as to what to enter at any MCI Mail prompt, typing a [?] and pressing the [Enter] key will display an explanation of available options. D.3 Internet Internet is an electronic mail system connecting governmen- tal institutions, military branches, educational institu- tions, and commercial companies. Only ASCII text messages up to 50,000 characters can be sent through this system. Internet is a connection of various systems. The message format will vary from one system to another. Check at your mail location for the correct format. Two things that must be known: ■ The User Id of Ernest Vogelsinger is 100015.551 (note that the comma changes to a period on Internet) ■ The CompuServe domain address is "compuserve.com". An typical example of the format used on the Internet sy- stem is: INTERNET: 100015.551@compuserve.com The format will vary, but the essential elements of the address will stay the same. D.4 Telex, Twx CompuServe Mail allows to receive messages from any TELEX or TWX machine in the world. The information the TELEX user needs to send a message to a CompuServe electronic mailbox is: ■ The User Id (100015,551) ■ The machine number to send the message to: 3762848 (which has the answerback of CompuServe) Specify on the first non-blank line of the message a "TO:" followed by the User ID to inform CompuServe Mail where to deliver the message. If a subject is desired, you also can add an "RE:" after the "TO:" line in the message. ----- DMalloc ------------------------------------------- Page 50 of 52 ----- The format would look as follows: TO: 100015,551 (This is required) CompuServe Inc. (This is optional) RE: DMalloc Registration (This is optional) Note: If you are using another electronic mail service to generate a TELEX to be sent to CompuServe, you need to first verify you can place the "TO:" information on the first non-blank line of the message. Some electronic mail systems automatically insert other information at the top of an outbound TELEX making it impossible for CompuServe Mail to determine the correct address. EasyLink is an electronic mail service from which CompuServe cannot currently receive inbound TELE- Xes. D.5 X.400 The address that you should specify to a mail system which can route messages to CompuServe via an X.400 connection is: Country = US ADMD = CompuServe PRMD = CSMail DDA = 100015.551(note the period instead of a comma) On AT&T Mail, for example, you could specify To: mhs/c=us/ad=compuserve/pd=csmail/- d.id=100015.551 AT&T has defined a gateway named mhs!csmail that may repla- ce the c=, ad=, and pd= information. On AT&T, you could also specify To: mhs!csmail!100015.551 Note: Again, the User Id must contain a period instead of a comma. ----- DMalloc ------------------------------------------- Page 51 of 52 ----- D.6 MHS You can send MHS messages to the CompuServe Mail Hub. Spe- cify the message adressee as MAIL@CSERVE {100015,551} Note: Some MHS applications do not have a specific proce- dure for entering the foreign address field. If you are unsure of the foreign address field capabili- ties of the MHS application, consult the documenta- tion or call the producers of the software to see if their package supports foreign address fields. If an MHS application does not specifically support the foreign address field, there may still be a way to address a message to a non-MHS address. In the space where the MHS address is normally entered, you may be able to enter the foreign address field. The foreign address field must be enclosed in braces. For example, at the TO: or CC: prompt enter: MAIL@CSERVE {100015,551} ----- DMalloc ------------------------------------------- Page 52 of 52 -----